# language: zh-CN
# 需求ID: REQ-006
# SRS需求: 6.1 RESTful API自动生成
# Feature ID: Epic 6.1
# 用户故事: US-018, US-019, US-020
功能: RESTful API自动生成
  作为开发者
  我希望能自动生成标准的CRUD API并支持DSL v2.0规范
  以便快速提供数据访问接口并支持类型别名和跨字段验证

  背景:
    假设我是一个使用RESTful API生成的开发者
    并且我已经定义了YAML DSL v2.0实体模型
    并且我希望快速提供API接口
    并且我使用了类型别名和参数化模板

  # US-018: 作为开发者，我希望能自动生成标准的CRUD API
  场景: 自动生成标准CRUD API支持DSL v2.0特性
    假设我从文件加载了一个用户实体定义: "tests/cucumber/fixtures/entities/user-dsl.yml"
    当系统生成API时
    那么应该自动创建以下端点:
      | 方法   | 路径           | 功能     |
      | POST   | /api/users     | 创建用户 |
      | GET    | /api/users     | 查询用户列表 |
      | GET    | /api/users/:id | 获取单个用户 |
      | PUT    | /api/users/:id | 更新用户 |
      | DELETE | /api/users/:id | 删除用户 |
    并且每个端点应该返回标准的HTTP状态码
    并且应该包含适当的错误处理
    并且应该支持类型别名的自动转换和验证
    并且应该在API响应中执行跨字段验证规则
    并且应该根据参数化模板动态生成API结构

  # US-019: 作为开发者，我希望API支持查询参数和分页
  场景: 支持查询参数和分页
    假设我请求用户列表API
    当我发送GET请求到/api/users
    并且包含查询参数:
      """
      GET /api/users?page=1&limit=10&sort=createdAt:desc&filter=age>18
      """
    那么应该返回分页的用户列表
    并且应该包含分页元数据:
      """
      {
        "data": [...],
        "pagination": {
          "page": 1,
          "limit": 10,
          "total": 100,
          "totalPages": 10
        }
      }
      """
    并且应该支持多种排序和过滤条件

  场景: HATEOAS导航支持
    假设我获取一个用户详情
    当我发送GET请求到/api/users/123
    那么响应应该包含HATEOAS链接:
      """
      {
        "id": "123",
        "name": "John Doe",
        "email": "john@example.com",
        "_links": {
          "self": { "href": "/api/users/123" },
          "update": { "href": "/api/users/123", "method": "PUT" },
          "delete": { "href": "/api/users/123", "method": "DELETE" },
          "orders": { "href": "/api/users/123/orders" },
          "profile": { "href": "/api/users/123/profile" }
        }
      }
      """
    并且链接应该基于用户权限动态生成
    并且应该包含关联资源的导航链接

  # US-020: 作为开发者，我希望支持关联资源的嵌套API
  场景: 关联资源的嵌套API
    假设从文件加载用户实体定义 "tests/cucumber/fixtures/entities/user-dsl.yml"
    当系统生成API时
    那么应该自动创建嵌套资源端点:
      | 方法   | 路径                    | 功能           |
      | GET    | /api/users/:id/orders   | 获取用户订单列表 |
      | POST   | /api/users/:id/orders   | 为用户创建订单  |
      | GET    | /api/users/:id/orders/:orderId | 获取用户特定订单 |
    并且应该自动处理关联关系的验证
    并且应该支持关联资源的级联操作

  场景: 业务命令API生成
    假设从文件加载用户实体定义 "tests/cucumber/fixtures/entities/user-dsl.yml"
    当系统生成API时
    那么应该自动创建命令端点:
      | 方法 | 路径                           | 功能     |
      | POST | /api/users/:id/activate        | 激活用户 |
      | POST | /api/users/:id/deactivate      | 停用用户 |
    并且应该验证命令输入参数
    并且应该在事务中执行命令
    并且应该发布相应的领域事件

  场景: API文档自动生成
    假设系统生成了API端点
    当我访问API文档端点
    那么应该提供完整的OpenAPI/Swagger文档
    并且应该包含所有端点的详细说明
    并且应该包含请求和响应的Schema定义
    并且应该包含示例请求和响应
    并且应该支持在线API测试功能

  场景: API版本管理
    假设我需要更新API版本
    当我修改DSL模型时
    那么系统应该支持API版本控制
    并且应该同时维护多个API版本
    并且应该提供版本迁移指南
    并且应该支持版本废弃策略

  场景: API安全和权限控制
    假设API需要权限控制
    当用户访问API端点时
    那么应该验证用户身份
    并且应该检查操作权限
    并且应该记录访问日志
    并且应该支持API密钥和JWT认证
    并且应该实现速率限制